Advanced Use of System Drop-Ins

As described in Section 15.3.1 System Drop-Ins, system drop-ins are special drop-in content elements that are named and controlled by LISTSERV Maestro. System drop-ins are only available for mailing lists that derive their recipients from data hosted by LISTSERV Maestro. They make it possible to include login and unsubscribe links to specific lists in the message are well as use other recipient data to create personalized messages.

The names of system drop-ins start with an asterisk “*”. System drop-ins need to be enclosed in the drop-in opening and closing tags just like normal drop-ins and drop-in usage needs to be enabled for the mail content, otherwise the system drop-ins will be ignored and will not be replaced. System drop-ins are replaced after normal drop-ins, so they can be nested within normal drop-in content elements.

This appendix is written using extensive examples to illustrate how and why system drop-ins can be used to create personalized message content for mail subscribers using hosted recipient data.

The login URL system drop-in is named *LoginURL. This name is case-sensitive and requires this exact spelling as well as the correct drop-in enclosing tags, for example “{{*LoginURL}}”.

This system drop-in is replaced with a URL that points to the login page for the member area of the hosted list that is used in the job’s recipient list. The URL will have a format similar to this:

•	Recipients type as target group, with a target group of the Based on Classic LISTSERV list type, where the LISTSERV list it is based on is a hosted LISTSERV list in LISTSERV Maestro.

Tip: Include the login URL system drop-in in email messages so that recipients can control their own subscription settings easily and without having to find or remember a long URL.

The unsubscribe URL system drop-in is named *UnsubscribeURL. This name is case-sensitive and requires this exact spelling as well as the correct drop-in enclosing tags, for example “{{*UnsubscribeURL}}”. This system drop-in is replaced with a URL that points to an unsubscribe page for the member area of the hosted list that is used in the job’s recipient list. The URL will have a format similar to this:

•	Recipients type as target group, with a target group of the Based on Classic LISTSERV list type, where the LISTSERV list it is based on is a hosted LISTSERV list in LISTSERV Maestro.

When creating the message content for an email job, you can now add a special system drop-in that will direct your subscribers to the External Profile Edit Page. This page will let your subscribers update specific profile fields without logging into the Membership Area.

The drop-in must be written in a special form because when you write this drop-in into your message you will need to include information about which profile fields will be queried from the subscriber. The syntax is as follows:

where FIELDNAME_LIST must be replaced with a comma-separated list of the names of all profile fields that the External Profile Edit Page will query from the subscriber.

will be replaced with an URL that points to an External Profile Edit Page that asks the subscriber to submit a value for the HOBBY profile field.

will be replaced with an URL that points to an External Profile Edit Page that will ask the subscriber to submit values for the STREET, ZIP_CODE, and CITY profile fields.

When defining the content for an HTML message, you can now use a new system drop-in, {{*ViewInBrowserURL}}, that will allow the recipient to view the HTML message in their own browser.

The system drop-in will be replaced with a http:// URL that points to a special page that displays the HTML part of your message. This lets the recipient view it in a separate browser window if, for some reason, the recipient can not view the HTML message in their own email client.

In an HTML message that also contains a text alternative part, you can use this system drop-in both in the HTML part and in the text alternative. By including the system drop-in in the text alternative, you will give those recipients that normally only view the text alternative the option of using the URL to display the full HTML message in a separate browser window.

Note: Viewing the message in a browser window will also display the HTML message with the same personalized merge values of the recipient as the original email. These merge values are coded into the URL. Therefore, in a mailing with a very large number of merge values (per recipient) and/or values with a very long text, this mechanism of coding the merge values into the URL may produce URLs that exceed the size limits imposed by the browser software that is in use. Consequently, you should limit the usage of this system drop-in to mailings where the merge field names and their values do not combine to form an excessively long URL.

Note: This system drop-in can not be used in messages that use conditional blocks (of the style .BB ... .EB). The only system merge fields (beginning with &*) allowed in the message are &*TO;, &*URLENCODE(...);, and &*INDEX;.

WARNING: The system drop-in for the multiple selection fields has been deprecated. It is still available for backwards compatibility with existing email jobs. For LISTSERV Maestro 4.0, please use the Formula Calculation system drop-in {{*Calc}}, with the "Count" and "SetToStringWithMaxLen" functions, as well as the "=", "<>", "<", "<=", ">", and ">=" set comparison operators.

Previous Versions	Version 4.0 and higher
Multiple Selection Field Count	use {{*Calc}} with the "Count" function
Multiple Selection Field Enumerated	use {{*Calc}} with the "SetToStringWithMaxLen" function
Multiple Selection Field Advanced Set-Operators	use {{*Calc}} with the "=", "<>", "<", "<=", ">" and ">=" set comparison operators. You can also use the "Count(&FIELD;)=0" function to check for the empty set.

Normally, multiple selection fields cannot be used for mail-merging. Mail merging is only compatible with fields that have a single value. Any field that was defined to allow subscribers to select more than one choice is classified as a multiple selection field. To work around this situation, a system drop-in has been introduced to allow merging the information from a multiple selection field into the text of a message. This system drop-in is only usable if the recipient type of the mail job is a target group of the Based on Hosted Recipient List type.

*Multi FIELD_NAME count

Replace “FIELD_NAME” with the name of the multiple selection field being used as the merge field. For example, a multiple selection field with the name “hobbies” would appear as “{{*Multi hobbies count}} “.

The directive is case-sensitive and requires this exact syntax and the correct drop-in enclosing tags. It will be replaced by the number of selections that each subscriber has made from the available choices of the profile field with the name “FIELD_NAME”. If a subscriber has selected 3 different items from the list, the number “3” will be dropped in the message body.

*Multi FIELD_NAME separated by "SEPARATOR"

Replace “FIELD_NAME” with the name of the multiple selection field being used as the merge field. Replace “SEPARATOR” with any string (which must be enclosed in quotation marks). This string will be used to separate the enumerated values if more than one choice has been made by the subscriber. For example, if a subscriber selected “surfing”, “poker”, and “reading” from a selection list field named “hobbies” and a comma with a space after it is the desired separator character in the mail text, then the drop-in would appear as “{{*Multi hobbies separated by “, ”}}” and produce a line suck as “surfing, poker, reading”. If the space is not included as part of the separator string, then only a comma will be used producing a line that reads like this: “surfing,poker,reading”.

Additional optional parameters are available for this type of system drop-in. They include:

•

default "CUSTOMIZED_DEFAULT" – If a subscriber does not have any of the choices selected, the drop-in would normally be replaced with an empty string. By setting a customized default parameter, all subscribers that do not have any selections will have the text inside the quotation marks dropped into the message. For example, a subscriber who did not select any hobbies from the multiple selection list could have the word “other” dropped into the message text. The drop-in would appear as “{{*Multi hobbies separated by “,” default “other”}}”

•

more "CUSTOMIZED_ELLIPSIS" – If a subscriber’s selections from the list are longer than approximately 800 characters, the enumeration will break off and be replaced with ellipsis “…”. By setting the customized ellipsis parameter, any text string may be added to the enumeration field, replacing the standard “…”. In addition, the number of items left off the list can be added by using “#COUNT” anywhere in the string. For example, if a subscriber selected “surfing”, “poker”, and “reading” from a selection list field named “hobbies, and a comma is the desired separator character in the mail text, then the drop-in would appear as “{{*Multi hobbies separated by “, ”}}” and the text “surfing,poker,reading” will be dropped into the message.

Here are some examples that use all these tools:

Assume a subscriber which has selected the hobbies “Cycling”, “Poker”, “Windsurfing”, “Bird Watching”, “Web-Browsing” and “Swimming” from a multiple selection listed named “HOBBIES”

The drop-in {{*Multi HOBBIES separated by ","}} will be replaced with:

“Cycling,Poker,Windsurfing,Bird Watching,Web-Browsing,Swimming” in the body of the message.

Note that there is no space after the comma separator, since none was included in the separator string of the directive. If the drop-in is rewritten as follows (note the space after the comma):

then the replacement text in the message body would look like this:

“Cycling, Poker, Windsurfing, Bird Watching, Web-Browsing, Swimming”

For the sake of the example, assume that the above string would be too long for the 800 characters threshold, which would be overstepped by “Bird Watching”. The replacement would then be abbreviated with the standard ellipsis token, like this:

“Cycling, Poker, Windsurfing, ...”

If this is not acceptable, a custom ellipsis token can be created:

The replacement text in the message body would then look like this:

“Cycling, Poker, Windsurfing, and others...”

To provide even more information, the #COUNT parameter can be added:

The replacement text in the message body would then look like this:

“Cycling, Poker, Windsurfing, and 3 more”

When a subscriber has not selected any hobbies the system drop-in

will then be replaced with no text at all. Leaving a blank spot in the message text.

To fill something in for subscribers who do not have anything selected, a default string can be created as follows:

{{*Multi HOBBIES separated by ", " default "<no hobby selected>"}}

The replacement text in the message body for only those subscribers with no hobbies selected would then look like this:

“<no hobby selected>”

These examples can be combined to cover those subscribers who have a few selections from the multiple selection list, many selections from the list, and no selections from the list like this:

{{*Multi HOBBIES separated by ", " default "<no hobby selected>" more "and #COUNT more"}}

The line break has been added for readability. In LISTSERV Maestro, this would have to be on one line. If both “default” and “more” are used, “default” must come first and “more” second.

The resulting replacement text would be different for different subscribers, depending on what, if anything, they had selected from the list. Subscribers with only a few selected values would get the correct comma (and space) separated list, for example:

“Cycling, Poker, Swimming”

Subscribers with too many values would get the abbreviated list with a customized ellipsis text, for example:

“Cycling, Poker, Windsurfing, and 3 more”

Subscribers without any selection would get a customized default text:

“<no hobby selected>”

•

Multiple Selection Field Advanced Set-Operators – This set of operators allows for the creation of drop-ins to personalize content for recipients based on their selections from the multiple selection field. This is a complex, yet very powerful tool that can be used to send specialized content to individual recipients based on their recipient data. For example, in a message to subscribers who selected a hobby or hobbies from the selection list, a special advertisement for Hawaiian vacations for those who selected “surfing” as one of their choices will be included. Hobbyists without surfing as a selection will not receive the ad, but will receive another general advertisement.

This type of system drop-in is based upon comparing two sets. The first set of items is taken from the multiple selection list, and the second set of items is created by the user. The two sets (two groups of items) can then be compared using four different operators to see what relationship they have to one another. The outcome of this comparison can be either “true” or “false” and will determine which content is dropped into which message.

The name of this version of drop-in is a directive with the following syntax:
*Multi [not] FIELD_NAME OP COMPARE_SET ? "TRUE_TEXT" : "FALSE_TEXT"

The directive is case-sensitive and requires this exact syntax and the correct drop-in enclosing tags.

Note: The brackets around the word “not” are not part of the syntax, but they are used to denoted that the word “not” itself is optional, meaning that it can be included (without brackets) or not.

Replace “FIELD_NAME” with the name of the multiple selection field being used as the merge field. The content of this field for any given subscriber defines the content of the first set of the comparison.

Replace “OP” with the set operator you want to employ for the comparison. Available operators are (without the quotes):

•	“<=”Subset – Checks if the first set is a subset of the second set. The first set is a subset of the second set if the first set is fully contained in the second set (all elements from the first set also are in the second set).

Note: If two sets are equal, then the subset condition is also true, meaning that the two equal sets are always also “trivial” subsets of each other. Except for the trivial case of equality, the first set is smaller than the second set.

•	“>=” Superset – Checks if the first set is a superset of the second set. The first set is a superset of the second set if the first set contains the entire second set (all elements from the second set also are in the first set).

Note: If two sets are equal then the superset condition is also true, meaning that the two equal sets are always also “trivial” supersets of each other. Except for the trivial case of equality, the first set is “larger” than the second set.

•

“&” Intersection – Checks if there is a non-empty intersection between the first and the second set. A non-empty intersection exists if at least one element of the first set also appears in the second set. It does not matter how many elements appear in both sets, as long as at least one appears in both, the intersection is non-empty and the check will result in “true”. In other words, the check is “true” if at least one element appears in the first set and in the second set.

Replace “COMPARE_SET” with the second set of the comparison. Specify this set as a comma-separated list of all values in the set. Each value must be enclosed within quotation marks <">. Type the textual names of those choices from the multiple selection field column specified in “FIELD_NAME” that are to be part of the second set. Enclose each name individually in quotes and use commas to separate the values if there is more than one.

Replace “TRUE_TEXT” with the drop-in text for comparisons that result in a “true” match and replace “FALSE_TEXT” with the drop-in text for comparisons that result in a “false” match. If the quote character <”> appears in the text of either field it must be escaped. To escape the quote character use it twice in a row.

For example, to send a special advertisement for Hawaiian vacations to all those subscribers who selected “surfing” as one of their hobbies in the multiple selection field “HOBBIES” in a mail job going out to all hobbyists, the system drop-in would appear like this: “{{*Multi HOBBIES & “surfing” ? "Follow your dreams and ride the big curl in Hawaii. See your travel agent today and mention this email offer for a 10% discount on hotel rates on the Sheraton on Waikiki" : "Visit your local Hobby Master store today! Check here for the nearest one ““http://www.hobbymaster.com”””}}

Some scenarios that can be used as examples that demonstrate system drop‑ins are given below. Line breaks that occur in the system drop-ins have been added for readability only.

Scenario 1: If the subscriber has selected exactly the three hobbies “Swimming”, “Cycling”, and “Poker” from the list “HOBBIES” (and no others), use one text for replacement, if not use a different text”.

This is a check of the type “equality”. If the set of hobbies selected by the subscriber (=first set) is equal to the set that contains the hobbies “Swimming”, “Cycling”, and “Poker” (=second set), the check will be “true”, otherwise it will be “false”. The corresponding drop-in looks like this:

Scenario 2: If the subscriber has selected one, two or all of the hobbies “Swimming”, “Cycling”, and “Poker” from the list “HOBBIES” use one text for replacement, if not use a different text.

This is a check of the type “subset”. If the set of hobbies selected by the subscriber (=first set) is a subset of the set that contains the hobbies “Swimming”, “Cycling”, and “Poker” (=second set), the check will be “true”, otherwise it will be “false”. The corresponding drop-in looks like this:

Scenario 3: If the subscriber has selected at least the hobby “Swimming” from the list “HOBBIES” (any other hobbies can be selected as well as long as “swimming” is included), use one text for replacement, if not use a different text.

This is a check of the type “superset”. If the set of hobbies selected by the subscriber (=first set) is a superset of the set that contains only the hobby “Swimming” (=second set), the check will be “true”, otherwise it will be “false”. The corresponding drop-in looks like this:

Scenario 4: If the subscriber has selected any of the hobbies “Swimming”, “Cycling”, and “Poker” (not necessarily all of them, and others not included can be selected) from the list “HOBBIES” use one text for replacement, if not use a different text.

This is a check of the type “intersection”. If the set of hobbies selected by the subscriber (=first set) intersects with the set that contains the hobbies “Swimming”, “Cycling”, and “Poker” (=second set), the check will be “true”, otherwise it will be “false”. The corresponding drop-in looks like this:

Note: Even though mathematically the “empty set” is always a subset of every other conceivable set, with regards to the “subset” operator in LISTSERV Maestro this is not so. In LISTSERV Maestro, if a subscriber has not selected any choices (=first set is the “empty set”) then the subset operator will always yield “false”.

When observing the “raw” drop-in, one text that will be used for replacement for subscribers who fulfill the condition and one text that will be used for replacement for all other subscribers who do not fulfill the condition are always required.

However, there are also possible scenarios such as “If subscribers have “Diving” among their hobbies, include an advertisement for the newest scuba gear. If not, do not include any additional content.” Other times a scenario could call for the text for one or both conditions to be very long or involved. This is usually not possible using a system drop-in since everything must be written on a single line.

For these types of scenarios, combining a system drop-in with conditional blocks can be the right solution. The advantage of using this method is that system drop-ins will be replaced before the content is evaluated for conditional blocks, meaning that the result of a system drop‑in replacement can be used in a LISTSERV condition.

To utilize the order of replacement for system drop-ins and conditional blocks to the best advantage, specify two very simple values to be returned in the “true” and “false” cases of the system drop-in. For example, use the words “true” and “false” or even the digits “1” and “0” for the replacement text. Next, use a LISTSERV condition to check for either of these values and conditionally include the desired content or not. For more information about conditional blocks, see Appendix E: Using Conditional Blocks.

Some scenarios that can be used as examples that demonstrate system drop‑ins combined with conditional blocks are given below. Line breaks that occur in the system drop-ins have been added for readability only.

Scenario 1: If the subscribers have “Diving” among their hobbies, listed in the multiple select field “HOBBIES” include an advertisement for the newest scuba gear. If not, do not include anything” can be written as:

Scenario 2: If subscribers have selected any of the hobbies for which there is a special this week, (specials are “Cycling”, “Poker” and “Diving” this week) then include HTML formatted content describing the special(s). If not, include some other HTML formatted content of a general nature. This can be written as (linebreaks in the drop-in added for readability only):

.BB (1 = {{*Multi HOBBIES & "Cycling", "Poker", "Diving" ? "1" : "0"}})
<h1>Weekly Hobbies Special</h1>
<p>Did you know that our current Weekly Hobbies Special covers some of the hobbies you are interested in?</p>
<p>Check it out at...</p>
etc...
.ELSE
<h1>General Text</h1>
<p>General text goes here...</p>
etc...
.EB

The name of this system drop-in is *Calc. The name is case-sensitive and requires this exact spelling, followed by a valid mathematical formula, and the appropriate enclosing tags, for example “{{*Calc ToDate(SubscribeTimeMillis,“MMMM dd, yyyy”)}}” will return a drop-in that reads the date the subscriber signed on to the list.

Merge fields from subscriber data can be combined with other merge fields or number- or text-constants and even predefined functions into a formula. The formula will then be calculated individually for each recipient to determine an individual drop-in replacement text for that recipient. If the formula contains merge-fields, the result will be calculated for each recipient and may differ from recipient to recipient.

Formulas can be used to calculate drop-in content based on existing recipient data to determine a birth date, a subscription date, a bank balance, and much more. Formulas must follow a set of rules that are detailed in Section 18 Calculation Formulas.

A scenario is described below that uses conditional blocks and calculation formulas to send customized messages to each recipient in a customer database. It is beyond the scope of this document to give all the possible ways formulas can be used to calculate personalized content. The scenario described below uses a merge-field value (a number) that is used in subtraction formulas with constant numbers to calculate the replacement values.

Scenario 1: A supermarket chain has a customer-card bonus-point system where customers are awarded points for every purchase. After collecting a certain number of points, customers can use their points to trade for bonus items. The bonus items with the highest values require more points. The recipient data has a column “CURRENT_POINTS” that contains the current total points for each subscriber. By using a calculation formula in conjunction with data in the “CURRENT_POINTS” column, content such as “You currently have X many points! This means that you only need Y points more to get a free watch or only Z points more to get a free digital camera!” can be created.

The supermarket decides that customers must earn 300 points for a free watch and 500 points for a free digital camera. From this information and depending on the value of “CURRENT_POINTS” there are four groups of customers:

In combination with LISTSERV’s conditional blocks, the following personalized content can be created to address each of the four groups and add the point balances for each individual..BB (&CURRENT_POINTS >= 800)

This means you are eligible to receive both a free watch and digital camera. Pick up your gifts at your nearest SuperMarket, and don’t forget to bring your bonus card with you. After collecting your gifts, you’ll still have{{*Calc &CURRENT_POINTS; - 800}} points left!

Congratulations! With your &CURRENT_POINTS; point balance, you are eligible for a free watch, which will leave you with {{*Calc &CURRENT_POINTS; – 300}} points remaining. You also qualify for a free digital camera, which will leave you with {{*Calc &CURRENT_POINTS; - 500}} points remaining.

You are on track! With your current point balance of &CURRENT_POINTS; you are eligible for a free watch, which will leave you {{*Calc &CURRENT_POINTS; – 300}} points, or you can collect {{*Calc 500 - &CURRENT_POINTS;}} more points to qualify for a digital camera!

Keep going! You already have &CURRENT_POINTS; collected! Only another
{{*Calc 300 - &CURRENT_POINTS;}} points to go and you can receive a free watch! Better yet, save {{*Calc 500 – CURRENT_POINTS;}} more points and receive a free digital camera
.EB

Important: Formulas offer many more features than illustrated in the scenario above. All the standard operators like +, -, *, /, and % (modulo) can be used in any combination and even be nested with parenthesis. Formulas can also work on text strings and there are a number of pre-defined functions, like abs, min, max, random, to-date, substring, and more. For details, see Section 18 Calculation Formulas.

Some of the system drop-ins allow users to include their own text for certain parameters. Any user-supplied text must usually be enclosed in quotation marks <"> to distinguish it from the surrounding drop-in directive text.

If the text itself contains the quote character anywhere (quotation marks appear somewhere in the text), it must be “escaped” so that the system drop-in is interpreted correctly. All quote characters in the actual text must be escaped by “doubling” them. This means that the character is used twice in succession with no space in between them. For example, to use this customized text:

LISTSERV Maestro contains a system drop-in that allows you to check if a given user drop-in actually has a non-empty content or not. The system drop-in itself will always be replaced either by the text "true" or "false" (without the quotes), depending on if the referenced user drop-in has a non-empty content or not.

A non-empty content is a content with at least one non-whitespace character in it. I.e. all content which is either totally empty or which contains only whitespace characters (like space, tab, linebreaks, etc.) is interpreted as empty.

This system drop-in is usually used in a conditional block where its result (which is always either "true" or "false") is used in the condition to decide if a conditional block shall be included in the mail or not. That way, it is for example possible to include a certain block only if a given user-drop is actually non-empty, or the other way round, include a certain block only if the user drop-in is empty.

Where "NAME" is the name of the user drop-in to check (do not specify the name of another system drop-in). The directive is case-sensitive, and it requires this exact syntax, the correct spelling of the user drop-in name, and the correct drop-in enclosing tags.

Assume that you have an auto-repeat job with a user drop-in called "DailyQuote" that pulls its content from a file. The job is sent on a daily basis and the content of the drop-in file is also updated daily, so that each day there is a different quote included. Only on some days there is actually no content at all for this drop-in. Now assume that in the part of the mail where this drop-in is included, there is also some short intro-text, which is only supposed to appear if the user drop-in is actually not empty. Also, if the user drop-in is empty, a suitable replacement text should appear instead. For this a conditional block with the *HasContent system drop-in can be used (indentations for readability only):

Assume that you have a job with a user drop-in called "Sample" that is included at some location in the mail job, where the drop-in also sometimes is empty. In case that it is empty, there is supposed to appear a certain alert text at another location in the same mail job. For this too a conditional block with the *HasContent system drop-in can be used (indentations for readability only):